
<HTML>

<HEAD>
<TITLE>HTTPClient FAQ</TITLE>
<LINK REV="made"     HREF="mailto:ronald@innovation.ch">
<LINK REL="Previous" HREF="index.html">
</HEAD>

<BODY BGCOLOR="#FFFFFF">


<H1>HTTPClient FAQ</H1>

<H2>Contents</H2>

<UL>
<LI><A HREF="#general">General</A>
    <UL>
    <LI><A HREF="#cookie_handler">How do I get rid of the Cookie-Popup</A>
    <LI><A HREF="#jdk">Will the HTTPClient work with JDK 1.3? (1.2, 1.1)</A>
    <LI><A HREF="#hang">Dialog box doesn't appear or hangs</A>
    <LI><A HREF="#handler">Displaying images and playing sound</A>
    <LI><A HREF="#formdata">File upload using multipart/form-data</A>
    <LI><A HREF="#url">UnknownHostException: http://www.foo.bar/x</A>
    <LI><A HREF="#ssl">https support</A>
    <LI><A HREF="#V0.4">When will V0.4 be out?</A>
    <LI><A HREF="#license">What are the licensing conditions?</A>
    <LI><A HREF="#diffres">I'm trying to emulate Netscape/Exploder/whatever
                           but I'm getting different results</A>
    <LI><A HREF="#hiddenf">I'm trying to POST to a form but I'm not getting
                           the expected results</A>
    <li><A HREF="#cookiesns">The site is saying "Your browser doesn't support
                             cookies"</A>
    <LI><A HREF="#multi_clients">How do I simulate multiple independent clients
	or users?</A>
    </UL>
<LI><A HREF="#applet">Applet specific</A>
    <UL>
    <LI><A HREF="#se-prop">SecurityException: properties</A>
    <LI><A HREF="#se-thread">SecurityException: thread</A>
    </UL>
<LI><A HREF="#application">Application specific</A>
    <UL>
    <LI><A HREF="#exit">Application doesn't exit</A>
    </UL>
</UL>

<H2><A NAME="general">General</A></H2>


<H4><A NAME="cookie_handler">Every time the server tries to set a cookie
    I get a pop-window asking whether I want to accept the cookie. How
    do I get rid of it?</A>
    </H4>

<BLOCKQUOTE>
    <P>If you just want to accept all cookies blindly then set the
    cookie-policy-handler to null:
    <PRE>
	CookieModule.setCookiePolicyHandler(null); </PRE>
    See the <A HREF="advanced_info.html#cookie_mod">advanced_info</A>
    doc for more information.
</BLOCKQUOTE>


<H4><A NAME="jdk">Will the HTTPClient work with JDK 1.3? (or 1.1, or
    1.2)</A>
    </H4>

<BLOCKQUOTE>
    <P>The HTTPClient will work fine with JDK 1.1 or later, including
    JDK 1.2 and JDK 1.3. Only JDK 1.0.2 is not supported anymore.
</BLOCKQUOTE>


<H4><A NAME="hang">All goes fine, until I try to do a request to a site
    that requires authorization or tries to set cookies. The dialog box
    either doesn't appear, or it appears but then everything hangs.</A>
    </H4>

<BLOCKQUOTE>
    <P>What you are probably doing is issuing the request from inside
    an AWT event handler. <strong>Don't!</strong> The problem is that
    while you're in an event handler no other events can get processed,
    including any event for the popup. This leads to a deadlock: no
    events can be processed till the popup has been closed again
    (thereby allowing the request to finish and to return to the
    caller), and the popup won't do anything unless it gets the
    corresponding event (e.g. a keyboard or mouse event).
    <P>There are various solutions to this:
    <OL>
    <LI>Don't do any request from inside an event handler. This can be
	achieved by either starting a new thread which does the request,
	or by setting a flag and having the main thread do it (this is
	the way it's done in the <A HREF="HTTPClientExample.html">Example
	Applet</A>).
    <LI>Install your own authorization and cookie policy handlers which
	don't use the AWT (see <A
	HREF="api/HTTPClient/AuthorizationInfo.html#setAuthHandler(HTTPClient.AuthorizationHandler)">AuthorizationInfo.setAuthHandler</A>
	and <A
	HREF="api/HTTPClient/CookieModule.html#setCookiePolicyHandler(HTTPClient.CookiePolicyHandler)">CookieModule.setCookiePolicyHandler</A>).
	However, I recommend the previous solution, as in general it is
	bad practice to do any sort of extended work inside an event
	handler (i.e. the code in the handler should execute quickly
	and return so that other events can be handled).
    <LI>If the site requires authorization then make the necessary
	authorization info available to the HTTPClient beforehand; see
	<A HREF="getting_started.html#auth">Authorization Handling</A>
	for more info.
    <LI>Use <A
	HREF="api/HTTPClient/HTTPConnection.html#setAllowUserInteraction(boolean)">HTTPConnection.setAllowUserInteraction()</A>
	or <A
	HREF="api/HTTPClient/HTTPConnection.html#setDefaultAllowUserInteraction(boolean)">HTTPConnection.setDefaultAllowUserInteraction()</A>
	to prevent the popups from being used. Note that this means that
	cookies will be silently accepted and that authorization info
	must be provided via the addXXXAuthorization() methods (see
	previous point).
    </OL>
</BLOCKQUOTE>


<H4><A NAME="handler">How can I display an image or play an audio file
    retrieved via the HTTPClient? Do I have to write my own
    ContentHandler's?</A></H4>

<BLOCKQUOTE>
    <P>You certainly could write your own ContentHandler's, but there
    is an easier way (however, one solution relies on undocumented sun
    classes):
    <DL>
    <DT>Sound (.au)
    <DD>This tip is from a <A HREF="http://www.javaworld.com/javaworld/javatips/jw-javatip24.html">JavaWorld article</A> by Chong Ser Wah.
	Assuming <var>resp</var> is the <var>HTTPResponse</var>, use the
	following construct:
	<PRE>
	    import sun.audio.AudioPlayer;
	    import sun.audio.AudioStream;

	    AudioStream as = new AudioStream(resp.getStream());
	    AudioPlayer.player.start(as); </PRE>
    <DT>Images (gif and jpeg)
    <DD>Assuming <var>resp</var> is the <var>HTTPResponse</var>, use the
	following:
	<PRE>
	    import java.awt.Toolkit;

	    Image img = ToolKit.getDefaultToolkit().createImage(resp.getData()); </PRE>
    </DL>
</BLOCKQUOTE>


<H4><A NAME="formdata">I would like to upload files using POST and the
    multipart/form-data encoding just like certain browsers do - how do I
    do this with the HTTPClient?</A></H4>

<BLOCKQUOTE>
    <P>See <A HREF="api/HTTPClient/Codecs.html#mpFormDataEncode(HTTPClient.NVPair[], HTTPClient.NVPair[], HTTPClient.NVPair[])">Codecs.mpFormDataEncode()</A>.
</BLOCKQUOTE>


<H4><A NAME="url">I'm having trouble creating a connection. All I get is
    <PRE>        java.net.UnknownHostException: http://www.foo.bar/x </PRE>
    The code I use looks like:
    <PRE>        con = new HTTPConnection("http://www.foo.bar"); </PRE>
    </A></H4>

<BLOCKQUOTE>
    <P>You are passing the wrong data to that particular constructor -
    it expects a <em>host name</em>, not a full url. Either use
    <PRE>        con = new HTTPConnection("www.foo.bar"); </PRE>
    or use something like
    <PRE>        con = new HTTPConnection(new URL("http://www.foo.bar")); </PRE>.
</BLOCKQUOTE>


<H4><A NAME="ssl">Does HTTPClient support <var>HTTPS</var> (i.e. HTTP on
    top of SSL)?</A></H4>

<BLOCKQUOTE>
    <P>No, not yet. This is on the top of the list of things to do for
    version 0.4. The only real problem is finding a suitable SSL
    implementation. However, see the <A HREF="https.html">https support</A>
    page for a list of patches available for various commercial SSL
    packages.
</BLOCKQUOTE>


<H4><A NAME="V0.4">When will V0.4 be available?</A></H4>

<BLOCKQUOTE>
    <P>I don't know. I'm fairly busy with a job and helping to renovate
    a house, so it'll definitely be a few months more.
</BLOCKQUOTE>

<H4><A NAME="license">May I use the HTTPClient in a commercial product?
    What are the conditions? How much does it cost?</A></H4>

<BLOCKQUOTE>
    <P>The HTTPClient is covered by the GNU <A HREF="../0LICENSE">Lesser
    General Public License</A> (LGPL). Note that this is
    <strong>not</strong> the same as the GPL, which is quite a bit more
    restrictive. One of the main differences is that the copyleft only
    applies to modifications of the library code itself, not to any
    product using the HTTPClient or to modules and handlers you write
    for the HTTPClient.

    <P>Here is a summary of the most important points:
    <UL>
    <LI>You may use the HTTPClient in any product you wish, whether
        commercial or otherwise. This product may be put under any
	license you wish (i.e. the HTTPClient's license is not
	infectious), and no source for the product need be distributed.
    <LI>The above liberties also apply to any modules and handlers you
        may have written for the HTTPClient.
    <LI>The HTTPClient itself is free for all uses, and will stay so.
        Others (including you) may however redistribute the HTTPClient
	too and charge for the cost of distribution.
    <LI>You may package the HTTPClient with your product, or you may
        even redistribute the HTTPClient by itself, provided you
	either distribute the complete HTTPClient package (including
	the source to it) or, if distributed over the net, provide
	pointers to where the source and the license to the HTTPClient
	can be obtained.
    <LI>You may make any modifications to the HTTPClient that you wish.
	However, if you distribute the modified HTTPClient then you must
	put those modifications under LGPL too and distribute them at no
	cost (or at the cost of distribution). This is the only infectious
	part of the license. Again, to restate: this applies only to
	modifications of the HTTPClient source itself.
    </UL>
</BLOCKQUOTE>

<H4><A NAME="diffres">I'm trying to emulate Netscape/Exploder/whatever
		      but I'm getting different results</A></H4>

<BLOCKQUOTE>
    <P>Here are a few things that may be causing problems:
    <UL>
	<LI>The site may be expecting certain browser types, i.e it may
	    be looking at the User-Agent field. You can try setting the
	    User-Agent header with something like the following:
	    <PRE>
            con.setDefaultHeaders(
                new NVPair[] { new NVPair("User-Agent", "Mozilla/4.5") });</PRE>
	    (do this before you send the request, of course).
	<LI>The site may be expecting a Referer header containing a valid
	    url. Try setting that header appropriately.
	<LI>The site may be requiring cookies. Try accepting any cookies it
	    sends.
    </UL>
</BLOCKQUOTE>

<H4><A NAME="hiddenf">I'm trying to POST a form but I'm not getting the
		      expected results</A></H4>

<BLOCKQUOTE>
    <P>Any number of things may be happening here too. But first, check
    that you are not forgetting any data. Many forms have hidden fields
    (<code>&lt;INPUT TYPE=HIDDEN NAME=... VALUE=...&gt;</code>). If you
    are taking an html form and trying to do the same request as a browser
    would then make sure your sending along the info from those fields too
    (the fields may be anywhere on the page, so look closely). Also, take
    a look at the <A HREF="emulating_forms.html">Emulating Forms</A> doc.
    If that isn't the problem, see <A HREF="#diffres">above</A>.
</BLOCKQUOTE>

<H4><A NAME="cookiesns">The site is saying "Your browser doesn't support
			cookies"</A></H4>

<BLOCKQUOTE>
    <P>yahoo.com and similarly broken sites just look at the User-Agent
    header to determine if the client supports cookies or not. Therefore,
    just set the header to something used by Netscape or Exploder.
    Example:
    <PRE>
    con.setDefaultHeaders(
            new NVPair[] { new NVPair("User-Agent", "Mozilla/4.5") });</PRE>
    (do this before you send the request, of course).
</BLOCKQUOTE>

<H4><A NAME="multi_clients">How do I simulate multiple independent clients or
			    users?</A></H4>

<BLOCKQUOTE>
    <P>See the section on <A HREF="advanced_info.html#contexts">Contexts</A> in
    the advanced-info doc.
</BLOCKQUOTE>

<HR>
<H2><A NAME="applet">Applet specific</A></H2>


<H4><A NAME="se-prop">I keep getting the message "#Security Exception:
    properties" (Netscape 3.x), "#Security Exception: checkpropsaccess.key"
    (Netscape 4.x), or
    "com.ms.security.SecurityExceptionEx[HTTPClient/HTTPConnection.&lt;clinit&gt;]:
    Unable to access system property:" (Internet Exploder) in the Java Console
    every time
    my Applet starts.</A></H4>

<BLOCKQUOTE>
    <P>These can be ignored. What is happening is that the static
    initializer of the HTTPConnection class tries to read a number of
    properties and this results in a SecurityException (in an Applet).
    These exceptions are caught inside the initializer, but Netscape's
    AppletSecurityManager and Exploder's StandardSecurityManager print the
    above messages before throwing each exception.
</BLOCKQUOTE>


<H4><A NAME="se-thread">I keep getting the message "#Security Exception:
    thread" in the Java Console.</A></H4>

<BLOCKQUOTE>
    <P>This one is a little trickier. I assume the HTTPClient is being
    called from an AWT event handler? Then what is happening is the
    following. To keep a connection from staying open indefinitely when
    using persistent connections, the HTTPClient uses a timeout thread
    to close the connection if it's been idle for more than 10
    seconds.  To prevent applications from hanging at exit this thread
    is made a daemon thread when created (using
    <code>setDaemon(true)</code>).  Furthermore, the thread is created
    when sending the first request, and is therefore created in the
    context of whatever thread is calling HTTPClient. The problem now is
    that the AWT event handler runs in thread of its own which belongs
    to the main thread group java.lang.ThreadGroup, but applets are only
    allowed to manipulate threads in the AppletThreadGroup (this
    includes stop()'ing a thread or doing a setDaemon()). Now if the
    HTTPClient is called from an event handler the timeout thread is
    created belonging to the main thread group, and any attempt at
    modifying it will therefore result in a security exception.

    <P>This message can actually be ignored too, as it doesn't matter
    whether the thread is a daemon or not in applets and the security
    exception is caught internally. However, it's not good practice to
    call HTTPClient from an event handler, as potentially long running
    stuff should be done in the main thread or a thread of its own
    (otherwise you lock up the event handling during that time). For an
    example of how to let the main thread do things see the simple <A
    HREF="HTTPClientExample.html">Example Applet</A>.
</BLOCKQUOTE>


<HR>
<H2><A NAME="application">Application specific</A></H2>


<H4><A NAME="exit">My application reaches the end, and then instead of
    exiting just hangs.</A></H4>

<BLOCKQUOTE>
    <P>What is probably happening is that there are some (non daemon) threads
    still around that haven't exited. An application won't exit until all
    (non daemon) threads are dead. Here is one reason why a thread might
    still be around (apart from any you might have started and not stopped
    yourself):
    <OL>
    <LI>The AWT uses a number of (non daemon) threads which are never
	killed.  If the authorization popup or the cookie handler popup
	appeared then these AWT threads were started and will therefore
	still be around at program exit time. In this case you need an
	explicit "<CODE>System.exit(0)</CODE>" at the end of your
	program.
    </OL>
</BLOCKQUOTE>


<P>
<A HREF="index.html">
<IMG SRC="images/back.gif" ALT="[HTTPClient]"></A>
<HR>

<ADDRESS>
Ronald Tschal&auml;r / 6. May 2001 /
<A HREF="mailto:ronald@innovation.ch">ronald@innovation.ch</A>.
</ADDRESS>

</BODY>

</HTML>

